What changed and why

claimDelivery had four terminal outcomes but only one emitted a queryable structured event field (the legacy dedup-skip). The claim-won happy path was completely silent, so the dedup hit-rate denominator and the fail-open rate were not queryable from structured logs. Tracked as issue #232.

Behaviour is unchanged — logging-only. The SET-NX-EX command, TTL, return values, control flow, and fail-open semantics are byte-for-byte identical.

Changes

• src/webhook/idempotency-log-fields.ts (new): z.discriminatedUnion("event", …) schema over the three-event family, mirroring src/utils/retry-log-fields.ts. Not a runtime validator on the hot path; it is the drift-prevention contract the co-located test parses each captured emit through. deliveryId stays camelCase (the established repo-wide child-logger ID binding); new metric fields use snake_case.
• src/webhook/idempotency.ts: claimDelivery now emits a uniform event on all 4 outcomes:
  • idempotency.claimed — info, new (was unlogged); SET-NX won, caller proceeds.
  • idempotency.duplicate_skipped — info; replaces the legacy "dedup-skip" literal.
  • idempotency.failed_open reason: "unavailable" — warn; Valkey unconfigured/disconnected (no SET issued).
  • idempotency.failed_open reason: "error" + err — warn; the SET threw.
• test/webhook/idempotency-log-fields.test.ts (new): strict-schema drift tests (accept well-formed events; reject unknown literals, extra fields, invalid/missing reason, empty deliveryId).
• test/webhook/idempotency.test.ts: upgraded to a recording logger; each captured emit is parsed through IdempotencyLogFieldsSchema to prove emit/schema agreement (closing the drift hole a loose string check leaves open). Return-value + SET-arg assertions preserved.
• docs/operate/observability.md: new ## Idempotency log fields section (events, levels, fields).

Flow

flowchart TD
    CDEntry["claimDelivery called"]:::gate
    CheckValkey{"Valkey available<br/>and healthy?"}:::gate
    DoSet["SET key NX EX 259200"]:::gate
    ErrThrown{"SET threw?"}:::gate
    ResOK{"result is OK?"}:::gate
    WarnUnavail["warn idempotency.failed_open<br/>reason unavailable, return true"]:::ev
    InfoClaimed["info idempotency.claimed<br/>return true"]:::ev
    InfoSkipped["info idempotency.duplicate_skipped<br/>return false"]:::ev
    WarnError["warn idempotency.failed_open<br/>reason error plus err, return true"]:::ev
    CDEntry --> CheckValkey
    CheckValkey -- no --> WarnUnavail
    CheckValkey -- yes --> DoSet
    DoSet --> ErrThrown
    ErrThrown -- yes --> WarnError
    ErrThrown -- no --> ResOK
    ResOK -- yes --> InfoClaimed
    ResOK -- no --> InfoSkipped
    classDef ev fill:#196f3d,color:#ffffff
    classDef gate fill:#2c3e50,color:#ffffff

Test plan

• test/webhook/idempotency-log-fields.test.ts — strict-schema drift (extra field / unknown event / bad reason / empty deliveryId rejected)
• test/webhook/idempotency.test.ts — all 4 outcomes asserted; each emit parsed through the schema; return-value + SET-arg checks kept
• dedup-skip literal retired (no remaining reference in src/)
• typecheck / lint / format / docs:build clean
• Full bun test: stash-baseline identical (1063 pass, 0 new failures); remaining failures are pre-existing local DB/Valkey-absent suites. Isolated CI runner is authoritative.

Closes #232

Summary by CodeRabbit

• Documentation

  • Enhanced observability documentation to detail webhook delivery deduplication events and their logging behavior.

• Tests

  • Added comprehensive test coverage for webhook idempotency event logging validation.